<HTML>
<BODY BGCOLOR=white>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
NAME
     drmaa_synchronize,       drmaa_wait,        drmaa_wifexited,
     drmaa_wexitstatus,     drmaa_wifsignaled,    drmaa_wtermsig,
     drmaa_wcoredump, drmaa_wifaborted - Waiting for jobs to fin-
     ish

SYNOPSIS
     #include "drmaa.h"

     int drmaa_synchronize(
          const char *job_ids[],
          signed long timeout,
          int dispose,
          char *error_diagnosis,
          size_t error_diag_len
     );

     int drmaa_wait(
          const char *job_id,
          char *job_id_out,
          size_t job_id_out_len,
          int *stat,
          signed long timeout,
          drmaa_attr_values_t **rusage,
          char *error_diagnosis,
          size_t error_diagnois_len
     );

     int drmaa_wifaborted(
          int *aborted,
          int stat,
          char *error_diagnosis,
          size_t error_diag_len
     );

     int drmaa_wifexited(
          int *exited,
          int stat,
          char *error_diagnosis,
          size_t error_diag_len
     );

     int drmaa_wifsignaled(
          int *signaled,
          int stat,
          char *error_diagnosis,
          size_t error_diag_len
     );

     int drmaa_wcoredump(
          int *core_dumped,
          int stat,
          char *error_diagnosis,
          size_t error_diag_len
     );

     int drmaa_wexitstatus(
          int *exit_status,
          int stat,
          char *error_diagnosis,
          size_t error_diag_len
     );

     int drmaa_wtermsig(
          char *signal,
          size_t signal_len,
          int stat,
          char *error_diagnosis,
          size_t error_diag_len
     );

DESCRIPTION
     The drmaa_synchronize() function blocks the  calling  thread
     until  all jobs specified in <I>job</I>_<I>ids</I> have failed or finished
     execution. If <I>job</I>_<I>ids</I> contains  'DRMAA_JOB_IDS_SESSION_ALL',
     then  this function waits for all jobs submitted during this
     DRMAA session. The <I>job</I>_<I>ids</I> pointer array must be  <I>NULL</I>  ter-
     minated.

     To prevent blocking indefinitely in this  call,  the  caller
     may use the <I>timeout</I>, specifying how many seconds to wait for
     this call to complete before timing out. The  special  value
     DRMAA_TIMEOUT_WAIT_FOREVER  can be used to wait indefinitely
     for a result. The special value DRMAA_TIMEOUT_NO_WAIT can be
     used to return immediately. If the call exits before <I>timeout</I>
     seconds, all the specified jobs have completed or  the  cal-
     ling  thread  received  an  interrupt.   In  both cases, the
     return code is DRMAA_ERRNO_EXIT_TIMEOUT.

     The <I>dispose</I> parameter specifies how to treat reaping  infor-
     mation.  If  '0'  is  passed  to  this parameter, job finish
     information will still be available  when  <B><A HREF="../htmlman3/drmaa_wait.html?pathrev=V62u5_TAG">drmaa_wait(3)</A></B>  is
     used.  If  '1'  is  passed,  <B><A HREF="../htmlman3/drmaa_wait.html?pathrev=V62u5_TAG">drmaa_wait(3)</A></B> will be unable to
     access this job's finish information.

  drmaa_wait()
     The drmaa_wait() function blocks the calling thread until  a
     job fails or finishes execution.  This routine is modeled on
     the   <B><A HREF="../htmlman3/wait4.html?pathrev=V62u5_TAG">wait4(3)</A></B>    routine.    If    the    special    string
     'DRMAA_JOB_IDS_SESSION_ANY'  is  passed as <I>job</I>_<I>id</I>, this rou-
     tine will wait for any job from the session.  Otherwise  the
     <I>job</I>_<I>id</I> must be the job identifier of a job or array job task
     that was submitted during the session.

     To prevent blocking indefinitely in this  call,  the  caller
     may  use  <I>timeout</I>,  specifying  how many seconds to wait for
     this call to complete before timing out. The  special  value
     DRMAA_TIMEOUT_WAIT_FOREVER can be to wait indefinitely for a
     result. The special value DRMAA_TIMEOUT_NO_WAIT can be  used
     to  return  immediately.  If  the  call exits before <I>timeout</I>
     seconds have passed, all the specified jobs  have  completed
     or the calling thread received an interrupt.  In both cases,
     the return code is DRMAA_ERRNO_EXIT_TIMEOUT.

     The routine reaps jobs on a successful call, so  any  subse-
     quent   calls   to   <B><A HREF="../htmlman3/drmaa_wait.html?pathrev=V62u5_TAG">drmaa_wait(3)</A></B>  will  fail  returning  a
     DRMAA_ERRNO_INVALID_JOB error,  meaning  that  the  job  has
     already  been  reaped.  This error is the same as if the job
     were unknown. Returning due to  an  elapsed  timeout  or  an
     interrupt  does  not cause the job information to be reaped.
     This means that, in this  case,  it  is  possible  to  issue
     <B><A HREF="../htmlman3/drmaa_wait.html?pathrev=V62u5_TAG">drmaa_wait(3)</A></B> multiple times for the same <I>job</I>_<I>id</I>.

     If <I>job</I>_<I>id</I>_<I>out</I> is not a null pointer, then on return  from  a
     successful  <B><A HREF="../htmlman3/drmaa_wait.html?pathrev=V62u5_TAG">drmaa_wait(3)</A></B> call, up to <I>job</I>_<I>id</I>_<I>out</I>_<I>len</I> charac-
     ters from the job id of  the  failed  or  finished  job  are
     returned.

     If <I>stat</I> is not a null pointer, then on return  from  a  suc-
     cessful  <B><A HREF="../htmlman3/drmaa_wait.html?pathrev=V62u5_TAG">drmaa_wait(3)</A></B> call, the status of the job is stored
     in the integer pointed to by <I>stat</I>.  <I>stat</I>  indicates  whether
     job  failed  or finished and other information. The informa-
     tion encoded in  the  integer  value  can  be  accessed  via
     <B><A HREF="../htmlman3/drmaa_wifaborted.html?pathrev=V62u5_TAG">drmaa_wifaborted(3)</A></B>  <B><A HREF="../htmlman3/drmaa_wifexited.html?pathrev=V62u5_TAG">drmaa_wifexited(3)</A></B> <B><A HREF="../htmlman3/drmaa_wifsignaled.html?pathrev=V62u5_TAG">drmaa_wifsignaled(3)</A></B>
     <B><A HREF="../htmlman3/drmaa_wcoredump.html?pathrev=V62u5_TAG">drmaa_wcoredump(3)</A></B> <B><A HREF="../htmlman3/drmaa_wexitstatus.html?pathrev=V62u5_TAG">drmaa_wexitstatus(3)</A></B> <B><A HREF="../htmlman3/drmaa_wtermsig.html?pathrev=V62u5_TAG">drmaa_wtermsig(3)</A></B>.

     If <I>rusage</I> is not a null pointer, then on return from a  suc-
     cessful <B><A HREF="../htmlman3/drmaa_wait.html?pathrev=V62u5_TAG">drmaa_wait(3)</A></B> call, a summary of the  resources used
     by the terminated job is returned in form of a DRMAA  values
     string   vector. The entries in the DRMAA values string vec-
     tor can  be  extracted  using  <B><A HREF="../htmlman3/drmaa_get_next_attr_value.html?pathrev=V62u5_TAG">drmaa_get_next_attr_value(3)</A></B>.
     Each string returned by <B><A HREF="../htmlman3/drmaa_get_next_attr_value.html?pathrev=V62u5_TAG">drmaa_get_next_attr_value(3)</A></B> will be
     of the  format  &lt;name&gt;=&lt;value&gt;,  where  &lt;name&gt;  and  &lt;value&gt;
     specify  name  and  amount of resources consumed by the job,
     respectively.  See <B><A HREF="../htmlman5/accounting.html?pathrev=V62u5_TAG">accounting(5)</A></B> for an explanation  of  the
     resource information.

  drmaa_wifaborted()
     The drmaa_wifaborted() function evaluates into  the  integer
     pointed  to by <I>aborted</I> a non-zero value if <I>stat</I> was returned
     from a job that ended before entering the running state.

  drmaa_wifexited()
     The drmaa_wifexited() function evaluates  into  the  integer
     pointed  to  by <I>exited</I> a non-zero value if <I>stat</I> was returned
     from a job that terminated normally. A zero value  can  also
     indicate  that  although the job has terminated normally, an
     exit status is not  available,  or  that  it  is  not  known
     whether   the   job   terminated  normally.  In  both  cases
     <B><A HREF="../htmlman3/drmaa_wexitstatus.html?pathrev=V62u5_TAG">drmaa_wexitstatus(3)</A></B> will not provide exit  status  informa-
     tion.  A  non-zero  value  returned in <I>exited</I> indicates more
     detailed   diagnosis   can   be   provided   by   means   of
     <B><A HREF="../htmlman3/drmaa_wifsignaled.html?pathrev=V62u5_TAG">drmaa_wifsignaled(3)</A></B>,          <B><A HREF="../htmlman3/drmaa_wtermsig.html?pathrev=V62u5_TAG">drmaa_wtermsig(3)</A></B>         and
     <B><A HREF="../htmlman3/drmaa_wcoredump.html?pathrev=V62u5_TAG">drmaa_wcoredump(3)</A></B>.

  drmaa_wifsignaled()
     The drmaa_wifsignaled() function evaluates into the  integer
     pointed to by <I>signaled</I> a non-zero value if <I>stat</I> was returned
     for a job that terminated due to the receipt of a signal.  A
     zero  value can also indicate that although the job has ter-
     minated due to the receipt of a signal, the  signal  is  not
     available, or it is not known whether the job terminated due
     to the receipt of a signal. In both cases  <B><A HREF="../htmlman3/drmaa_wtermsig.html?pathrev=V62u5_TAG">drmaa_wtermsig(3)</A></B>
     will  not  provide  signal  information.  A  non-zero  value
     returned in <I>signaled</I> indicates  signal  information  can  be
     retrieved by means of <B><A HREF="../htmlman3/drmaa_wtermsig.html?pathrev=V62u5_TAG">drmaa_wtermsig(3)</A></B>.

  drmaa_wcoredump()
     If <B><A HREF="../htmlman3/drmaa_wifsignaled.html?pathrev=V62u5_TAG">drmaa_wifsignaled(3)</A></B> returned a  non-zero  value  in  the
     <I>signaled</I> parameter, the drmaa_wcoredump() function evaluates
     into the integer pointed to by <I>core</I>_<I>dumped</I> a non-zero  value
     if a core image of the terminated job was created.

  drmaa_wexitstatus()
     If <B><A HREF="../htmlman3/drmaa_wifexited.html?pathrev=V62u5_TAG">drmaa_wifexited(3)</A></B>  returned  a  non-zero  value  in  the
     <I>exited</I> parameter, the drmaa_wexitstatus() function evaluates
     into the integer pointed to by <I>exit</I>_<I>code</I> the exit code  that
     the  job  passed to <B><A HREF="../htmlman2/exit.html?pathrev=V62u5_TAG">exit(2)</A></B> or the value that the child pro-
     cess returned from main.

  drmaa_wtermsig()
     If <B><A HREF="../htmlman3/drmaa_wifsignaled.html?pathrev=V62u5_TAG">drmaa_wifsignaled(3)</A></B> returned a  non-zero  value  in  the
     <I>signaled</I>  parameter, the drmaa_wtermsig() function evaluates
     into  <I>signal</I>  up  to  <I>signal</I>_<I>len</I>  characters  of  a   string
     representation  of the signal that caused the termination of
     the job. For signals declared by POSIX.1, the symbolic names
     are  returned  (e.g.,  SIGABRT,  SIGALRM).  For  signals not
     declared by POSIX, any other string may be returned.

ENVIRONMENTAL VARIABLES
     SGE_ROOT       Specifies the location of the Sun Grid Engine
                    standard configuration files.

     SGE_CELL       If set, specifies the default Sun Grid Engine
                    cell to be used. To address a Sun Grid Engine
                    cell Sun Grid Engine uses (in  the  order  of
                    precedence):

                         The name of the cell  specified  in  the
                         environment  variable SGE_CELL, if it is
                         set.

                         The  name  of  the  default  cell,  i.e.
                         default.


     SGE_DEBUG_LEVEL
                    If  set,  specifies  that  debug  information
                    should  be written to stderr. In addition the
                    level of detail in which debug information is
                    generated is defined.

     SGE_QMASTER_PORT
                    If set,  specifies  the  tcp  port  on  which
                    <B><A HREF="../htmlman8/sge_qmaster.html?pathrev=V62u5_TAG">sge_qmaster(8)</A></B> is expected to listen for com-
                    munication requests.  Most installations will
                    use  a  services  map entry instead to define
                    that port.

RETURN VALUES
     Upon      successful      completion,       drmaa_run_job(),
     drmaa_run_bulk_jobs(),  and  drmaa_get_next_job_id()  return
     DRMAA_ERRNO_SUCCESS. Other values indicate an error.  Up  to
     <I>error</I>_<I>diag</I>_<I>len</I>  characters of error related diagnosis infor-
     mation is then provided in the buffer <I>error</I>_<I>diagnosis</I>.

ERRORS
     The  drmaa_synchronize(),  drmaa_wait(),  drmaa_wifexited(),
     drmaa_wexitstatus(),  drmaa_wifsignaled(), drmaa_wtermsig(),
     drmaa_wcoredump(), and drmaa_wifaborted() will fail if:

  DRMAA_ERRNO_INTERNAL_ERROR
     Unexpected  or  internal  DRMAA  error,  like  system   call
     failure, etc.

  DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
     Could not contact DRM system for this request.

  DRMAA_ERRNO_AUTH_FAILURE
     The specified request is not processed successfully  due  to
     authorization failure.

  DRMAA_ERRNO_INVALID_ARGUMENT
     The input value for an argument is invalid.

  DRMAA_ERRNO_NO_ACTIVE_SESSION
     Failed because there is no active session.

  DRMAA_ERRNO_NO_MEMORY
     Failed allocating memory.
     The drmaa_synchronize() and drmaa_wait() functions will fail
     if:

  DRMAA_ERRNO_EXIT_TIMEOUT
     Time-out condition.

  DRMAA_ERRNO_INVALID_JOB
     The job specified by the does not exist.

     The drmaa_wait() will fail if:

  DRMAA_ERRNO_NO_RUSAGE
     This error code is returned by drmaa_wait() when a  job  has
     finished but no rusage and stat data could be provided.

SEE ALSO
     <B><A HREF="../htmlman3/drmaa_submit.html?pathrev=V62u5_TAG">drmaa_submit(3)</A></B>.



































</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
